openapi: 3.0.0
info:
  version: "1.0.0"
  title: GeoServer Workspace
  description: A workspace is a grouping of data stores. Similar to a namespace, it is used
    to group data that is related in some way.

security:
  - basicAuth: []

tags:
  - name: workspaces
    description: Workspaces API

paths:
  /workspaces:
    get:
      tags:
        - workspaces
      operationId: getWorkspaces
      summary: Get a list of workspaces
      description: Displays a list of all workspaces on the server.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                  $ref: "#/components/schemas/WorkspacesResponse"
              examples:
                response:
                  value: >
                    {
                      "workspaces": {
                      "workspace": [
                        {
                         "name": "topp",
                         "href": "http://localhost:8080/geoserver/rest/workspaces/topp.json"
                        },
                        {
                          "name": "it.geosolutions",
                          "href": "http://localhost:8080/geoserver/rest/workspaces/it.geosolutions.json"
                        }
                      ]
                      }
                    }
        "401":
          description: Unauthorized
    post:
      tags:
        - workspaces
      operationId: createWorkspace
      summary: add a new workspace to GeoServer
      description: Adds a new workspace to the server
      parameters:
        - name: default
          in: query
          description: New workspace will be the used as the default. Allowed values are true or false,  The default value is false.
          required: false
          schema:
            type: boolean
            default: false
      requestBody:
        $ref: "#/components/requestBodies/Workspace"
      responses:
        "201":
          description: Created
          headers:
            Location:
              description: URL where the newly created workspace can be found
              schema:
                type: string
         #Note: ignoring the response here because geoserver returns a single unquoted string both for JSON and XML
         #responses and it can't be parsed either way. It should return only text/plain or a properly encoded response for the output content type
         # content:
         #   application/json:
         #     schema:
         #       type: string
        "401":
          description: Unable to add workspace as it already exists

  /workspaces/{workspace}:
    parameters:
      - name: workspace
        in: path
        description: the name of the workspace to fetch
        required: true
        schema:
          type: string
    get:
      tags:
        - workspaces
      operationId: getWorkspace
      summary: Retrieve a Workspace
      description: Retrieves a single workspace definition.
      parameters:
        - in: query
          name: quietOnNotFound
          required: false
          schema:
             type: boolean
             default: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                title: GetWorkspaceResponse
                properties:
                  workspace:
                    $ref: "#/components/schemas/WorkspaceSummary"
              examples:
                response:
                  value: >
                    {

                    "workspace": {
                      "name": "topp",
                      "dataStores": "http://localhost:8080/geoserver/rest/workspaces/topp/datastores.json",
                      "coverageStores": "http://localhost:8080/geoserver/rest/workspaces/topp/coveragestores.json",
                      "wmsStores": "http://localhost:8080/geoserver/rest/workspaces/topp/wmsstores.json"
                    }

                    }
        "404":
          description: workspace does not exist
    put:
      tags:
        - workspaces
      summary: Update a workspace
      description: takes the body of the post and modifies the workspace from it.
      operationId: modifyWorkspace
      responses:
        "200":
          description: Modified
        "404":
          description: Workspace not found
        "405":
          description: Forbidden to change the name of the workspace
      requestBody:
        $ref: "#/components/requestBodies/Workspace"
    delete:
      tags:
        - workspaces
      operationId: deleteWorkspace
      parameters:
        - name: recurse
          in: query
          description: delete workspace contents (default false)
          required: false
          schema:
            type: boolean
      responses:
        "200":
          description: Success workspace deleted
        "403":
          description: Workspace or related Namespace is not empty (and recurse not true)
        "404":
          description: Workspace doesn't exist
        "405":
          description: Can't delete default workspace
          
components:
  securitySchemes:
    basicAuth:     # <-- arbitrary name for the security scheme
      type: http
      scheme: basic

  requestBodies:
    Workspace:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/WorkspaceWrapper"
      description: The Workspace body information to upload.
      required: true
  schemas:
    WorkspaceWrapper:
      type: object
      title: Wrapper object around Workspace, in order to conform to how XStream serializes to JSON in GeoServer
      properties:
        workspace:
          $ref: "catalog.yaml#/components/schemas/WorkspaceInfo"

    WorkspaceSummary:
      title: Workspace Response
      type: object
      properties:
        name:
          type: string
          description: Name of workspace
        isolated:
          type: boolean
          default: false
        dataStores:
          type: string
          description: URL to Datas tores in this workspace
        coverageStores:
          type: string
          description: URL to Coverage stores in this workspace
        wmsStores:
          type: string
          description: URL to WMS stores in this workspace

    WorkspacesResponse:
      type: object
      properties:
        workspaces:
          type: object
          title: WorkspaceResponseWrapper
          properties:
            workspace:
              $ref: "catalogresponses.yaml#/components/schemas/NamedLinks"
